home *** CD-ROM | disk | FTP | other *** search
/ Windows Expert / Windows Expert.iso / windownt / rcsdoc.zip / RCSINTRO.TXT < prev    next >
Text File  |  1991-11-10  |  12KB  |  261 lines
  1.  
  2.  
  3. RCSINTRO(1)                Unix Programmer's Manual                RCSINTRO(1)
  4.  
  5.  
  6. NNNAAAMMMEEE
  7.      rcsintro - introduction to RCS commands
  8.  
  9. DDDEEESSSCCCRRRIIIPPPTTTIIIOOONNN
  10.      The Revision Control System (RCS) manages multiple  revisions  of  files.
  11.      RCS  automates  the  storing,  retrieval,  logging,  identification,  and
  12.      merging of revisions.  RCS is useful for text that is revised frequently,
  13.      for example programs, documentation, graphics, papers, and form letters.
  14.  
  15.      The basic user interface is extremely simple.  The novice only  needs  to
  16.      learn  two  commands:  ccciii(1) and cccooo(1).  ccciii, short for check in, deposits
  17.      the contents of a file into an archival file called an RCS file.  An  RCS
  18.      file  contains  all  revisions of a particular file.  cccooo, short for check
  19.      out, retrieves revisions from an RCS file.
  20.  
  21.      +o    Store and retrieve multiple revisions of text.  RCS  saves  all  old
  22.           revisions  in  a space efficient way.  Changes no longer destroy the
  23.           original,  because  the  previous   revisions   remain   accessible.
  24.           Revisions  can be retrieved according to ranges of revision numbers,
  25.           symbolic names, dates, authors, and states.
  26.  
  27.      +o    Maintain a complete  history  of  changes.   RCS  logs  all  changes
  28.           automatically.   Besides  the  text of each revision, RCS stores the
  29.           author, the date and time of check-in, and a log message summarizing
  30.           the  change.  The logging makes it easy to find out what happened to
  31.           a module, without having to compare source  listings  or  having  to
  32.           track down colleagues.
  33.  
  34.      +o    Resolve access conflicts.  When two  or  more  programmers  wish  to
  35.           modify  the  same  revision, RCS alerts the programmers and prevents
  36.           one modification from corrupting the other.
  37.  
  38.      +o    Maintain a tree of revisions.  RCS can maintain  separate  lines  of
  39.           development  for  each  module.   It  stores  a  tree structure that
  40.           represents the ancestral relationships among revisions.
  41.  
  42.      +o    Merge revisions  and  resolve  conflicts.   Two  separate  lines  of
  43.           development  of  a  module  can  be  coalesced  by  merging.  If the
  44.           revisions to be merged affect the same sections of code, RCS  alerts
  45.           the user about the overlapping changes.
  46.  
  47.      +o    Control releases and  configurations.   Revisions  can  be  assigned
  48.           symbolic  names  and  marked as released, stable, experimental, etc.
  49.           With these facilities, configurations of modules  can  be  described
  50.           simply and directly.
  51.  
  52.      +o    Automatically identify each revision  with  name,  revision  number,
  53.           creation time, author, etc.  The identification is like a stamp that
  54.           can be embedded at an appropriate place in the text of  a  revision.
  55.           The  identification  makes it simple to determine which revisions of
  56.           which modules make up a given configuration.
  57.  
  58.      +o    Minimize secondary storage.  RCS needs little extra  space  for  the
  59.           revisions  (only  the  differences).   If intermediate revisions are
  60.           deleted,  the  corresponding  deltas  are  compressed   accordingly.
  61.           Suppose  you  have  a file fff...ccc that you wish to put under control of
  62.  
  63.  
  64.                                     \*(Dt                                    1
  65.  
  66.  
  67.  
  68. RCSINTRO(1)                Unix Programmer's Manual                RCSINTRO(1)
  69.  
  70.  
  71.           RCS.  Invoke the check-in command
  72.  
  73.           ccciii  fff...ccc
  74.  
  75.      This command creates the RCS file fff...ccc,,,vvv, stores fff...ccc into it  as  revision
  76.      1.1,  and  deletes  fff...ccc.   It  also  asks  you  for  a  description.  The
  77.      description should be a synopsis of the contents of the file.  All  later
  78.      check-in  commands  will  ask you for a log entry, which should summarize
  79.      the changes that you made.
  80.  
  81.      Files ending in ,,,vvv are called RCS files  (v  stands  for  versions);  the
  82.      others are called working files.  To get back the working file fff...ccc in the
  83.      previous example, use the check-out command
  84.  
  85.           cccooo  fff...ccc
  86.  
  87.      This command extracts the latest revision from fff...ccc,,,vvv and writes  it  into
  88.      fff...ccc.   If you want to edit fff...ccc, you must lock it as you check it out with
  89.      the command
  90.  
  91.           cccooo  ---lll  fff...ccc
  92.  
  93.      You can now edit fff...ccc.
  94.  
  95.      Suppose after some editing you want to know what changes  that  you  have
  96.      made.  The command
  97.  
  98.           rrrcccsssdddiiiffffff  fff...ccc
  99.  
  100.      tells you the difference between the most recently checked-in version and
  101.      the working file.  You can check the file back in by invoking
  102.  
  103.           ccciii  fff...ccc
  104.  
  105.      This increments the revision number properly.
  106.  
  107.      If ccciii complains with the message
  108.  
  109.           ccciii eeerrrrrrooorrr::: nnnooo llloooccckkk ssseeettt bbbyyy _y_o_u_r _n_a_m_e
  110.  
  111.      then you have tried to check in a file even though you did  not  lock  it
  112.      when  you checked it out.  Of course, it is too late now to do the check-
  113.      out  with  locking,  because  another  check-out  would  overwrite   your
  114.      modifications.  Instead, invoke
  115.  
  116.           rrrcccsss  ---lll  fff...ccc
  117.  
  118.      This command will lock the latest revision for you, unless somebody  else
  119.      got  ahead  of  you already.  In this case, you'll have to negotiate with
  120.      that person.
  121.  
  122.      Locking assures that you, and only you, can check in the next update, and
  123.      avoids nasty problems if several people work on the same file.  Even if a
  124.      revision is locked, it can still be checked out for  reading,  compiling,
  125.      etc.  All that locking prevents is a _c_h_e_c_k-_i_n by anybody but the locker.
  126.  
  127.  
  128.  
  129.                                     \*(Dt                                    2
  130.  
  131.  
  132.  
  133. RCSINTRO(1)                Unix Programmer's Manual                RCSINTRO(1)
  134.  
  135.  
  136.      If your RCS file is private, i.e., if you are  the  only  person  who  is
  137.      going  to deposit revisions into it, strict locking is not needed and you
  138.      can turn it off.  If strict locking is turned off, the owner of  the  RCS
  139.      file  need  not  have  a lock for check-in; all others still do.  Turning
  140.      strict locking off and on is done with the commands
  141.  
  142.           rrrcccsss  ---UUU  fff...ccc     and     rrrcccsss  ---LLL  fff...ccc
  143.  
  144.      If you don't want to clutter  your  working  directory  with  RCS  files,
  145.      create  a subdirectory called RRRCCCSSS in your working directory, and move all
  146.      your RCS files there.  RCS commands will look first into  that  directory
  147.      to  find needed files.  All the commands discussed above will still work,
  148.      without any modification.  (Actually, pairs of RCS and working files  can
  149.      be  specified  in  three  ways:  (a) both are given, (b) only the working
  150.      file is given, (c) only the RCS file is  given.   Both  RCS  and  working
  151.      files  may  have  arbitrary  path  prefixes;  RCS  commands  pair them up
  152.      intelligently.)
  153.  
  154.      To avoid the deletion of the working file during check-in  (in  case  you
  155.      want to continue editing or compiling), invoke
  156.  
  157.           ccciii  ---lll  fff...ccc     or     ccciii  ---uuu  fff...ccc
  158.  
  159.      These commands check in fff...ccc as usual, but perform an implicit  check-out.
  160.      The  first  form  also  locks  the  checked  in  revision, the second one
  161.      doesn't.  Thus, these options save  you  one  check-out  operation.   The
  162.      first  form  is useful if you want to continue editing, the second one if
  163.      you just want to read the file.  Both update the  identification  markers
  164.      in your working file (see below).
  165.  
  166.      You can give ccciii the number you want assigned to a  checked  in  revision.
  167.      Assume  all  your  revisions  were  numbered 1.1, 1.2, 1.3, etc., and you
  168.      would like to start release 2.  The command
  169.  
  170.           ccciii  ---rrr222  fff...ccc     or     ccciii  ---rrr222...111  fff...ccc
  171.  
  172.      assigns the number 2.1 to the new revision.  From then on, ccciii will number
  173.      the  subsequent  revisions  with  2.2,  2.3,  etc.   The corresponding cccooo
  174.      commands
  175.  
  176.           cccooo  ---rrr222  fff...ccc     and     cccooo  ---rrr222...111  fff...ccc
  177.  
  178.      retrieve  the  latest  revision  numbered  2._x  and  the  revision   2.1,
  179.      respectively.   cccooo  without a revision number selects the latest revision
  180.      on the _t_r_u_n_k, i.e. the highest revision with a number consisting  of  two
  181.      fields.   Numbers with more than two fields are needed for branches.  For
  182.      example, to start a branch at revision 1.3, invoke
  183.  
  184.           ccciii  ---rrr111...333...111  fff...ccc
  185.  
  186.      This command starts a branch numbered 1 at revision 1.3, and assigns  the
  187.      number 1.3.1.1 to the new revision.  For more information about branches,
  188.      see rrrcccsssfffiiillleee(5).  RCS can put special strings for identification into your
  189.      source and object code.  To obtain such identification, place the marker
  190.  
  191.  
  192.  
  193.  
  194.                                     \*(Dt                                    3
  195.  
  196.  
  197.  
  198. RCSINTRO(1)                Unix Programmer's Manual                RCSINTRO(1)
  199.  
  200.  
  201.           $$$IIIddd$$$
  202.  
  203.      into your text, for instance inside a comment.   RCS  will  replace  this
  204.      marker with a string of the form
  205.  
  206.           $$$IIIddd:::  _f_i_l_e_n_a_m_e  _r_e_v_i_s_i_o_n  _d_a_t_e  _t_i_m_e  _a_u_t_h_o_r  _s_t_a_t_e  $$$
  207.  
  208.      With such a marker on the first page of each module, you can  always  see
  209.      with  which  revision  you are working.  RCS keeps the markers up to date
  210.      automatically.  To propagate the markers into your  object  code,  simply
  211.      put them into literal character strings.  In C, this is done as follows:
  212.  
  213.           static char rcsid[] = "$Id$";
  214.  
  215.      The command iiidddeeennnttt extracts such markers from any file, even  object  code
  216.      and  dumps.   Thus,  iiidddeeennnttt  lets  you  find  out which revisions of which
  217.      modules were used in a given program.
  218.  
  219.      You may also find it useful to put  the  marker  $$$LLLoooggg$$$  into  your  text,
  220.      inside  a  comment.   This  marker  accumulates the log messages that are
  221.      requested during check-in.  Thus, you can maintain the  complete  history
  222.      of   your   file  directly  inside  it.   There  are  several  additional
  223.      identification markers; see cccooo(1) for details.
  224.  
  225. IIIDDDEEENNNTTTIIIFFFIIICCCAAATTTIIIOOONNN
  226.      Author: Walter F. Tichy.
  227.      Revision Number: 5.0; Release Date: 1990/08/22.
  228.      Copyright (c) 1982, 1988, 1989 by Walter F. Tichy.
  229.      Copyright (c) 1990 by Paul Eggert.
  230.  
  231. SSSEEEEEE AAALLLSSSOOO
  232.      ci(1), co(1), ident(1),  rcs(1),  rcsdiff(1),  rcsintro(1),  rcsmerge(1),
  233.      rlog(1)
  234.      Walter F. Tichy, RCS--A System for Version Control, _S_o_f_t_w_a_r_e--_P_r_a_c_t_i_c_e  &
  235.      _E_x_p_e_r_i_e_n_c_e 111555, 7 (July 1985), 637-654.
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.                                     \*(Dt                                    4
  260.  
  261.